### Install SmartMotion with packer.nvim

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Quick-Start

This code snippet demonstrates how to install the smart-motion.nvim plugin using the packer.nvim package manager. It configures the plugin with various presets enabled during setup.

```lua
use {
  "FluxxField/smart-motion.nvim",
  config = function()
    require("smart-motion").setup({
      presets = {
        words = true,
        lines = true,
        search = true,
        delete = true,
        yank = true,
        change = true,
        paste = true,
        treesitter = true,
        diagnostics = true,
        git = true,
        quickfix = true,
        marks = true,
        misc = true,
      },
    })
  end,
}
```

--------------------------------

### Complete Smart-Motion.nvim Configuration Example

Source: https://context7.com/fluxxfield/smart-motion.nvim/llms.txt

This example demonstrates a comprehensive configuration for Smart-Motion.nvim, showcasing various features like custom keybindings, flow timeouts, auto-selection, custom highlights, and enabling specific presets. It also includes examples of registering custom motions for specific actions.

```lua
{
  "FluxxField/smart-motion.nvim",
  config = function()
    local sm = require("smart-motion")
    local registries = require("smart-motion.core.registries"):get()
    local merge = require("smart-motion.core.utils").action_utils.merge

    sm.setup({
      -- Colemak-friendly keys
      keys = "arstneiodhqwfpgjluy",

      -- Longer flow timeout
      flow_state_timeout_ms = 400,

      -- Auto-jump on single target
      auto_select_target = true,

      -- Custom highlights
      highlight = {
        hint = { fg = "#FF6B6B", bold = true },
        two_char_hint = { fg = "#4ECDC4" },
        dim = "Comment",
      },

      -- Enable specific presets with customizations
      presets = {
        words = { e = false, ge = false },  -- Keep native e and ge
        lines = true,
        search = true,
        treesitter = true,
        diagnostics = true,
        git = true,
        quickfix = true,
        marks = true,
        misc = true,
      },

      -- Disable native search labels
      native_search = false,
    })

    -- Register custom motion: jump to word and yank
    sm.motions.register("<leader>y", {
      collector = "lines",
      extractor = "words",
      filter = "filter_words_after_cursor",
      visualizer = "hint_start",
      action = merge({ "jump", "yank" }),
      map = true,
      modes = { "n" },
    })

    -- Register custom motion: multi-window function search
    sm.motions.register("<leader>F", {
      collector = "treesitter",
      extractor = "pass_through",
      filter = "filter_visible",
      visualizer = "hint_start",
      action = "jump_centered",
      map = true,
      modes = { "n" },
      metadata = {
        motion_state = {
          ts_node_types = {
            "function_declaration",
            "function_definition",
            "method_definition",
          },
          multi_window = true,
        },
      },
    })
  end,
}
```

--------------------------------

### Install SmartMotion with lazy.nvim

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Quick-Start

This code snippet shows how to install the smart-motion.nvim plugin using the lazy.nvim package manager. It includes options to enable various presets for enhanced motion capabilities.

```lua
{
  "FluxxField/smart-motion.nvim",
  opts = {
    presets = {
      words = true,
      lines = true,
      search = true,
      delete = true,
      yank = true,
      change = true,
      paste = true,
      treesitter = true,
      diagnostics = true,
      git = true,
      quickfix = true,
      marks = true,
      misc = true,
    },
  },
}
```

--------------------------------

### Install SmartMotion.nvim with lazy.nvim

Source: https://context7.com/fluxxfield/smart-motion.nvim/llms.txt

This snippet shows how to install the SmartMotion.nvim plugin using the lazy.nvim package manager. It includes basic configuration options such as the characters used for hint labels, flow state timeout, and enabling/disabling various preset motion groups.

```lua
{
  "FluxxField/smart-motion.nvim",
  opts = {
    -- Characters used for hint labels (home row first for speed)
    keys = "fjdksleirughtynm",

    -- Flow state timeout in milliseconds
    flow_state_timeout_ms = 300,

    -- Automatically jump when only one target exists
    auto_select_target = false,

    -- Show labels during native / search (toggle with <C-s>)
    native_search = true,

    -- Disable dimming of non-target text
    disable_dim_background = false,

    -- Enable preset groups
    presets = {
      words = true,        -- w, b, e, ge
      lines = true,        -- j, k
      search = true,       -- s, S, f, F, t, T, ;, ,, gs
      delete = true,       -- d, dt, dT, rdw, rdl
      yank = true,         -- y, yt, yT, ryw, ryl
      change = true,       -- c, ct, cT
      paste = true,        -- p, P
      treesitter = true,   -- ]], [[, ]c, [c, ]b, [b, daa, caa, yaa, dfn, cfn, yfn, saa, gS, R
      diagnostics = true,  -- ]d, [d, ]e, [e
      git = true,          -- ]g, [g
      quickfix = true,     -- ]q, [q, ]l, [l
      marks = true,        -- g', gm
      misc = true,         -- . (repeat), gmd, gmy
    },
  },
}
```

--------------------------------

### Complete Smart Motion Plugin Configuration Example

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Configuration

A comprehensive example of configuring the smart-motion.nvim plugin using the `opts` table. This includes custom key mappings, flow timeout, auto-select, custom highlights, and enabling/disabling various presets.

```lua
{
  "FluxxField/smart-motion.nvim",
  opts = {
    -- Colemak-friendly keys
    keys = "arstneiodhqwfpgjluy",

    -- Slightly longer flow timeout
    flow_state_timeout_ms = 400,

    -- Auto-jump on single target
    auto_select_target = true,

    -- Custom highlights
    highlight = {
      hint = { fg = "#FF6B6B", bold = true },
      two_char_hint = { fg = "#4ECDC4" },
      dim = "Comment",
    },

    -- Enable most presets, customize some
    presets = {
      words = true,
      lines = true,
      search = {
        s = true,
        S = true,
        f = true,
        F = true,
        t = true,
        T = true,
        gs = false,  -- don't need visual select
      },
      delete = true,
      yank = true,
      change = true,
      paste = false,  -- use native paste
      treesitter = true,
      diagnostics = true,
      git = true,
      quickfix = true,
      marks = true,
      misc = true,
    },

    -- Disable native search labels
    native_search = false,
  },
}
```

--------------------------------

### Override Motion Settings in Smart Motion

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Presets

Illustrates how to configure motion settings within presets for smart-motion.nvim. This example shows how to register the 'w' motion for the 'words' preset but not map it automatically, allowing for manual mapping later.

```lua
presets = {
  words = {
    w = {
      map = false,  -- register but don't map (map manually later)
    },
  },
}
```

--------------------------------

### Lazy.nvim Plugin Installation for SmartMotion.nvim

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Home

This snippet shows how to install and configure the SmartMotion.nvim plugin using the lazy.nvim package manager. It enables various presets for different types of motions, such as words, lines, search, and Treesitter integration.

```lua
{
  "FluxxField/smart-motion.nvim",
  opts = {
    presets = {
      words = true,        -- w, b, e, ge
      lines = true,        -- j, k
      search = true,       -- s, S, f, F, t, T, ;, , 
      delete = true,       -- d, dt, dT, rdw, rdl
      yank = true,         -- y, yt, yT, ryw, ryl
      change = true,       -- c, ct, cT
      paste = true,        -- p, P
      treesitter = true,   -- ]], [[, ]c, [c, ]b, [b, daa, caa, yaa, dfn, cfn, yfn, saa, gS, R
      diagnostics = true,  -- ]d, [d, ]e, [e
      git = true,          -- ]g, [g
      quickfix = true,     -- ]q, [q, ]l, [l
      marks = true,        -- g', gm
      misc = true,         -- . (repeat), gmd, gmy
    },
  },
}
```

--------------------------------

### Run Neovim with a Test Configuration

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Debugging

Launches Neovim using a specific test configuration file (`test_config.lua`). This is the recommended way to test plugin development and custom configurations without affecting your main setup.

```bash
nvim -u test_config.lua somefile.lua
```

--------------------------------

### Operator-Pending Mode Examples (Vimscript)

Source: https://github.com/fluxxfield/smart-motion.nvim/blob/master/README.md

Demonstrates how SmartMotion motions can be used with standard Vim operators in operator-pending mode. These examples show actions like indenting, uppercasing, auto-indenting, and formatting based on selected text objects.

```vimscript
>w    — indent from cursor to labeled word
gUw   — uppercase from cursor to labeled word
=j    — auto-indent from cursor to labeled line
gqj   — format from cursor to labeled line
>]]   — indent from cursor to labeled function
```

--------------------------------

### Lua Example: Combine Jump, Delete, and Center Actions

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Building-Custom-Motions

Demonstrates combining multiple actions using the `merge` utility. This example creates a motion that jumps to a target, deletes the target text, and then centers the screen. This is useful for creating complex, chained operations with a single keybinding.

```lua
-- Jump, delete, and center
action = merge({ "jump", "delete", "center" })
```

--------------------------------

### Enable Debug Logging and Setup SmartMotion

Source: https://github.com/fluxxfield/smart-motion.nvim/blob/master/docs/Debugging.md

Sets up smart-motion.nvim with debug logging enabled and custom highlight settings. It also demonstrates registering a custom motion for development purposes.

```lua
-- test_config.lua
vim.g.smart_motion_log_level = "debug"

require("smart-motion").setup({
  presets = {
    words = true,
  },
  highlight = {
    hint = { fg = "#FF0000", bg = "#FFFF00" },
  },
})

-- Test custom motion
require("smart-motion").register_motion("test", {
  collector = "lines",
  extractor = "words",
  filter = "default",
  visualizer = "hint_start",
  action = function(ctx, cfg, motion_state)
    print("Targets:", #motion_state.targets)
    print("Selected:", vim.inspect(motion_state.selected_jump_target))
  end,
  map = true,
  modes = { "n" },
  trigger = "<leader>t",
})
```

--------------------------------

### Treesitter Collector: Raw Query Example

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Pipeline-Architecture

Configuration example for the Treesitter collector using a raw query. This mode allows for precise selection of syntax nodes based on a Treesitter query string.

```lua
motion_state = {
  ts_query = "(function_declaration name: (identifier) @name) @func",
}
```

--------------------------------

### Smart Motion Plugin Configuration with Config Function

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Configuration

An example demonstrating how to configure the smart-motion.nvim plugin using a `config` function for more granular control. This allows for calling `sm.setup()` and registering custom motions and modules.

```lua
{
  "FluxxField/smart-motion.nvim",
  config = function()
    local sm = require("smart-motion")

    sm.setup({
      keys = "fjdksleirughtynm",
      presets = {
        words = true,
        search = true,
        treesitter = true,
      },
    })

    -- Register custom motions after setup
    sm.register_motion("<leader>j", {
      collector = "lines",
      extractor = "words",
      filter = "filter_words_after_cursor",
      visualizer = "hint_start",
      action = "jump_centered",
      map = true,
      modes = { "n", "v" },
    })

    -- Register custom modules
    local registries = require("smart-motion.core.registries"):get()
    registries.filters.register("my_filter", MyFilterModule)
  end,
}
```

--------------------------------

### Enable Selective Presets in Smart Motion Configuration

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Presets

Demonstrates how to enable specific presets for the smart-motion.nvim plugin, such as 'search', 'treesitter', and 'diagnostics', while leaving others disabled.

```lua
presets = {
  search = true,
  treesitter = true,
  diagnostics = true,
  -- others are disabled
}
```

--------------------------------

### Example of Registering a 'gw' Motion in SmartMotion

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/API-Reference

An example demonstrating the registration of a 'gw' motion. This motion is configured to collect lines, extract words, use a specific filter and visualizer, and perform a 'jump_centered' action, mapped to normal, visual, and operator-pending modes.

```lua
require("smart-motion").register_motion("gw", {
  collector = "lines",
  extractor = "words",
  filter = "filter_words_after_cursor",
  visualizer = "hint_start",
  action = "jump_centered",
  map = true,
  modes = { "n", "v", "o" },
  metadata = {
    label = "Jump to word",
    description = "Jump to a word after cursor",
    motion_state = {
      multi_window = false,
    },
  },
})
```

--------------------------------

### Selective Preset Enabling in SmartMotion

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Quick-Start

This Lua code snippet illustrates how to selectively enable specific presets for the smart-motion.nvim plugin. This allows users to customize functionality without overriding native Neovim keys.

```lua
presets = {
  -- Only enable these presets
  search = true,
  treesitter = true,
  diagnostics = true,
}
```

--------------------------------

### Combine Actions with Merge

Source: https://context7.com/fluxxfield/smart-motion.nvim/llms.txt

Demonstrates how to use `merge_actions` to create compound operations that execute multiple actions sequentially. Examples include jumping and yanking a word, yanking without moving the cursor, and jumping, deleting, and centering the screen.

```lua
local sm = require("smart-motion")
local merge = require("smart-motion.core.utils").action_utils.merge

sm.setup({ presets = {} })

-- Create a motion that jumps to a word and yanks it in one action
sm.motions.register("gy", {
  collector = "lines",
  extractor = "words",
  filter = "filter_words_after_cursor",
  visualizer = "hint_start",
  action = merge({ "jump", "yank" }),     -- Jump first, then yank the target
  map = true,
  modes = { "n" },
})

-- Create a motion that yanks without moving cursor (remote yank)
sm.motions.register("gY", {
  collector = "lines",
  extractor = "words",
  filter = "filter_words_around_cursor",
  visualizer = "hint_start",
  action = merge({ "yank", "restore" }),  -- Yank, then restore cursor position
  map = true,
  modes = { "n" },
})

-- Create a motion that jumps, deletes, and centers screen
sm.motions.register("gD", {
  collector = "lines",
  extractor = "words",
  filter = "filter_words_after_cursor",
  visualizer = "hint_start",
  action = merge({ "jump", "delete", "center" }),
  map = true,
  modes = { "n" },
})
-- Usage: Press gy -> select word -> cursor jumps to word and word is yanked
```

--------------------------------

### Configure Highlight Customization in Lua

Source: https://github.com/fluxxfield/smart-motion.nvim/blob/master/README.md

Demonstrates how to customize highlight groups for smart-motion.nvim using Lua. It shows examples of setting custom colors for 'hint' and 'two_char_hint', and assigning an existing highlight group 'Comment' to 'dim'.

```lua
highlight = {
  hint = { fg = "#FF2FD0" },
  two_char_hint = { fg = "#2FD0FF" },
  dim = "Comment",
}
```

--------------------------------

### Composing Actions in SmartMotion (Lua)

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Why-SmartMotion

Illustrates the concept of true composability in SmartMotion, where operators and motions can be freely combined. This example shows how to create compound actions by merging predefined actions like 'jump', 'delete', 'yank', and 'center'.

```lua
-- Operator 'd' + motion 'w' = delete to word
-- Operator 'y' + motion 'j' = yank to line
-- Operator 'c' + motion ']]' = change to function

-- And you can create compound actions:
action = merge({ "jump", "delete" })
action = merge({ "jump", "yank", "center" })
```

--------------------------------

### Customizing SmartMotion Hint Characters

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Quick-Start

This Lua code snippet demonstrates how to customize the hint characters used by smart-motion.nvim. Users can define their preferred set of keys for labels, with the first character being the most common.

```lua
opts = {
  keys = "fjdksleirughtynm",  -- default
  -- or for Colemak:
  -- keys = "arstneio",
}
```

--------------------------------

### Registering and Retrieving Modules from Registries in Lua

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/API-Reference

Shows examples of how to register a new module (e.g., a filter) with a given name and how to retrieve existing modules by their name or key. This is essential for extending the plugin's functionality.

```lua
-- Register a module
registries.filters.register("my_filter", MyModule)

-- Get by name
local filter = registries.filters.get_by_name("my_filter")

-- Get by key (for infer)
local extractor = registries.extractors.get_by_key("w")
```

--------------------------------

### Register a Custom Motion in SmartMotion

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Debugging

Registers a new custom motion named 'test' in smart-motion.nvim. This example defines the motion's behavior, visualization, and mapping, demonstrating how to extend the plugin's functionality.

```lua
-- Test custom motion
require("smart-motion").register_motion("test", {
  collector = "lines",
  extractor = "words",
  filter = "default",
  visualizer = "hint_start",
  action = function(ctx, cfg, motion_state)
    print("Targets:", #motion_state.targets)
    print("Selected:", vim.inspect(motion_state.selected_jump_target))
  end,
  map = true,
  modes = { "n" },
  trigger = "<leader>t",
})
```

--------------------------------

### Creating a Custom Filter Module

Source: https://github.com/fluxxfield/smart-motion.nvim/blob/master/docs/Building-Custom-Motions.md

Provides an example of creating a custom filter module for smart-motion.nvim. The filter keeps only targets containing the text 'TODO'. It shows how to define the filter's run function and register it.

```lua
local M = {}

function M.run(targets, ctx, cfg, motion_state)
  -- Keep only targets containing "TODO"
  return vim.tbl_filter(function(target)
    return target.text:match("TODO")
  end, targets)
end

return M
```

```lua
require("smart-motion.core.registries"):get().filters.register("todo_only", M)
```

--------------------------------

### Customizing SmartMotion Highlight Colors

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Quick-Start

This Lua code snippet shows how to customize the highlight colors for hints in smart-motion.nvim. Users can define specific foreground colors for regular hints, two-character hints, and dim text.

```lua
opts = {
  highlight = {
    hint = { fg = "#FF2FD0" },
    two_char_hint = { fg = "#2FD0FF" },
    dim = "Comment",
  },
}
```

--------------------------------

### Excluding Keys from SmartMotion Presets

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Quick-Start

This Lua code snippet shows how to enable a preset in smart-motion.nvim while excluding specific keys. This provides granular control over keybindings, preventing conflicts with existing ones.

```lua
presets = {
  words = {
    e = false,   -- don't override 'e'
    ge = false,  -- don't override 'ge'
  },
  search = true,
}
```

--------------------------------

### Logging Messages in Lua

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/API-Reference

Shows how to use the `log` module from `smart-motion.core.log` to output debug, info, warning, and error messages. It also includes an example of how to enable logging by setting a global variable.

```lua
local log = require("smart-motion.core.log")

log.debug("Debug message")
log.info("Info message")
log.warn("Warning message")
log.error("Error message")

-- Enable logging:
vim.g.smart_motion_log_level = "debug"  -- or "info", "warn", "error", "off"
```

--------------------------------

### Logging Messages with Smart Motion

Source: https://github.com/fluxxfield/smart-motion.nvim/blob/master/docs/API-Reference.md

Shows how to use the `log` module to output messages at different severity levels (debug, info, warn, error). It also includes an example of how to enable logging globally by setting a Vim variable.

```lua
local log = require("smart-motion.core.log")

log.debug("Debug message")
log.info("Info message")
log.warn("Warning message")
log.error("Error message")
```

```lua
vim.g.smart_motion_log_level = "debug"  -- or "info", "warn", "error", "off"
```

--------------------------------

### Treesitter Collector: Raw Query Example

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Building-Custom-Motions

Demonstrates using the `ts_query` metadata option with the Treesitter collector. This allows for full Treesitter query syntax to define the target nodes, providing maximum flexibility in selecting code elements.

```lua
metadata = {
  motion_state = {
    ts_query = "(function_declaration) @func",
  },
}

```

--------------------------------

### Input-Based Extractor Example

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Pipeline-Architecture

An example of an extractor that requires user input, specifically a single character. It utilizes `vim.fn.getchar()` to capture user input and sets it in `motion_state.search_text`.

```lua
M.before_input_loop = function(ctx, cfg, motion_state)
  -- Get character from user
  local char = vim.fn.getchar()
  motion_state.search_text = vim.fn.nr2char(char)
end
```

--------------------------------

### Essential SmartMotion Configuration Options

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Quick-Start

This Lua code snippet outlines essential configuration options for smart-motion.nvim. It covers hint characters, flow state timeout, auto-selection of targets, native search behavior, and background dimming.

```lua
opts = {
  -- Hint characters (first char = most common)
  keys = "fjdksleirughtynm",

  -- Flow state timeout (ms) - how long between motions to stay in "flow"
  flow_state_timeout_ms = 300,

  -- Auto-jump when only one target exists
  auto_select_target = false,

  -- Show labels during native / search (toggle with <C-s>)
  native_search = true,

  -- Dim non-target text
  disable_dim_background = false,
}
```

--------------------------------

### Treesitter Collector: Node Type Matching Example

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Pipeline-Architecture

Configuration example for the Treesitter collector to match specific node types. It yields any node that matches the provided type names.

```lua
motion_state = {
  ts_node_types = { "function_declaration", "method_definition" },
}
```

--------------------------------

### Treesitter Collector: Child Yielding Example

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Pipeline-Architecture

Configuration example for the Treesitter collector that yields individual children of container nodes. This is useful for extracting elements like arguments or parameters separately.

```lua
motion_state = {
  ts_node_types = { "arguments", "parameters" },
  ts_yield_children = true,
  ts_around_separator = true,  -- include commas
}
```

--------------------------------

### Treesitter Collector: Child Field Extraction Example

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Pipeline-Architecture

Configuration example for the Treesitter collector that extracts a specific child field from matching nodes. It yields only the content of the specified field (e.g., 'name').

```lua
motion_state = {
  ts_node_types = { "function_declaration" },
  ts_child_field = "name",
}
```

--------------------------------

### Configure SmartMotion with Presets and Custom Highlight

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Debugging

Sets up the smart-motion.nvim plugin with predefined word presets and custom highlight colors for hints. This demonstrates basic configuration options for visual feedback.

```lua
require("smart-motion").setup({
  presets = {
    words = true,
  },
  highlight = {
    hint = { fg = "#FF0000", bg = "#FFFF00" },
  },
})
```

--------------------------------

### SmartMotion Neovim Plugin Default Configuration

Source: https://github.com/fluxxfield/smart-motion.nvim/blob/master/README.md

Presents the default configuration for the smart-motion.nvim plugin. This includes settings for hint keys, highlighting, preset enablement, timeouts, and various behavioral options like auto-selection and native search integration.

```lua
{
  -- Characters used for hint labels (home row first for speed)
  keys = "fjdksleirughtynm",

  -- Use background highlighting instead of character replacement
  use_background_highlights = false,

  -- Highlight groups (string = existing group, table = custom definition)
  highlight = {
    hint = "SmartMotionHint",               -- { fg = "#FF2FD0" }
    hint_dim = "SmartMotionHintDim",
    two_char_hint = "SmartMotionTwoCharHint", -- { fg = "#2FD0FF" }
    two_char_hint_dim = "SmartMotionTwoCharHintDim",
    dim = "SmartMotionDim",                 -- "Comment"
    search_prefix = "SmartMotionSearchPrefix",
    search_prefix_dim = "SmartMotionSearchPrefixDim",
  },

  -- Enable/disable preset groups
  presets = {},

  -- Flow state timeout in milliseconds
  flow_state_timeout_ms = 300,

  -- Disable dimming of non-target text
  disable_dim_background = false,

  -- Maximum motions stored in repeat history
  history_max_size = 20,

  -- Automatically select when only one target exists
  auto_select_target = false,

  -- Enable label overlay during native / search (toggle with <C-s>)
  native_search = true,
}
```

--------------------------------

### Custom Filter Logic Example

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Pipeline-Architecture

Illustrates the structure for a custom filter function in Lua. Filters process a list of targets and return a subset based on specified criteria. The example shows a basic filter that keeps targets on lines greater than the cursor line.

```lua
function M.run(targets, ctx, cfg, motion_state)
  return vim.tbl_filter(function(target) 
    -- Your filtering logic
    return should_keep(target)
  end, targets)
end
```

--------------------------------

### Built-in Collectors Reference and Examples in Lua

Source: https://context7.com/fluxxfield/smart-motion.nvim/llms.txt

This Lua code provides a reference for the built-in collectors available in smart-motion.nvim, such as 'lines', 'treesitter', 'diagnostics', 'git_hunks', 'quickfix', 'marks', and 'history'. It also includes two examples demonstrating how to use the 'treesitter' collector with a custom query and the 'diagnostics' collector with severity filtering.

```lua
-- Collector reference table
local collectors = {
  lines       = "All buffer lines",
  treesitter  = "Syntax nodes (see ts_node_types, ts_query options)",
  diagnostics = "LSP diagnostics (filter with diagnostic_severity)",
  git_hunks   = "Git changed regions (via gitsigns or git diff)",
  quickfix    = "Quickfix/location list entries",
  marks       = "Vim marks (a-z local, A-Z global)",
  history     = "SmartMotion jump history",
}

-- Example: treesitter collector with raw query
sm.motions.register("example1", {
  collector = "treesitter",
  metadata = {
    motion_state = {
      ts_query = "(function_declaration name: (identifier) @name) @func",
    },
  },
  -- ... other options
})

-- Example: diagnostics collector with severity filter
sm.motions.register("example2", {
  collector = "diagnostics",
  metadata = {
    motion_state = {
      diagnostic_severity = { vim.diagnostic.severity.ERROR, vim.diagnostic.severity.WARN },
    },
  },
  -- ... other options
})
```

--------------------------------

### Motion State Configuration Options

Source: https://context7.com/fluxxfield/smart-motion.nvim/llms.txt

Demonstrates how to configure motion behavior using the `motion_state` option within `sm.motions.register`. This allows for fine-grained control over direction, window management, Treesitter integration, diagnostics, sorting, and search parameters.

```lua
-- Common motion_state options
sm.motions.register("example", {
  collector = "lines",
  extractor = "words",
  filter = "filter_words_after_cursor",
  visualizer = "hint_start",
  action = "jump",
  map = true,
  modes = { "n" },
  metadata = {
    motion_state = {
      -- Direction control
      direction = "after",              -- or "before"

      -- Multi-window support
      multi_window = true,              -- Show labels across all visible windows

      -- Treesitter options
      ts_node_types = { "function_declaration" },
      ts_child_field = "name",          -- Extract specific named field
      ts_yield_children = true,         -- Yield container children separately
      ts_around_separator = true,       -- Include separators in range
      ts_query = "(func) @cap",         -- Raw treesitter query

      -- Diagnostic options
      diagnostic_severity = vim.diagnostic.severity.ERROR,

      -- Sorting
      sort_by = "sort_weight",          -- Sort by metadata field
      sort_descending = false,          -- Sort direction

      -- Search options
      num_of_char = 2,                  -- Character limit for f/t motions
      exclude_target = true,            -- For till motions (t/T)

      -- Selection options
      auto_select_target = true,        -- Auto-jump on single target
    },
  },
})

```

--------------------------------

### Combine Actions for Custom Motion in Lua

Source: https://github.com/fluxxfield/smart-motion.nvim/blob/master/README.md

Shows how to register a custom motion that combines multiple actions using the `sm.merge_actions` function. This example creates a motion that both jumps to a target and yanks it.

```lua
local sm = require("smart-motion")

sm.motions.register("jump_and_yank", {
  collector = "lines",
  extractor = "words",
  filter = "filter_words_after_cursor",
  visualizer = "hint_start",
  action = sm.merge_actions({ "jump", "yank" }),
  map = true,
  modes = { "n" },
  trigger = "<leader>y",
})
```

--------------------------------

### Register Custom Motion with Multi-Window Support

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Advanced-Features

Example of registering a custom motion that utilizes multi-window capabilities. This allows labels to appear across all visible windows for enhanced navigation.

```lua
require("smart-motion").register_motion("<leader>s", {
  collector = "lines",
  extractor = "live_search",
  filter = "filter_visible",
  visualizer = "hint_start",
  action = "jump_centered",
  map = true,
  modes = { "n" },
  metadata = {
    motion_state = {
      multi_window = true,
    },
  },
})
```

--------------------------------

### Create Custom Action Module

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Building-Custom-Motions

Illustrates how to create a custom action module for smart-motion.nvim. The example action displays a notification with the text of the selected jump target. It also includes the code for registering the custom action and using it in motion configurations.

```lua
local M = {}

function M.run(ctx, cfg, motion_state)
  local target = motion_state.selected_jump_target
  if not target then return end

  -- Do something with the target
  vim.notify("Selected: " .. target.text)
end

return M
```

```lua
require("smart-motion.core.registries"):get().actions.register("notify_target", M)
```

```lua
action = "notify_target"
```

--------------------------------

### Registering a Custom Motion in SmartMotion (Lua)

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Why-SmartMotion

Demonstrates how to register a new motion within SmartMotion using its Lua API. This example shows the definition of the built-in 'w' motion, illustrating the use of collector, extractor, filter, visualizer, action, and modes.

```lua
require("smart-motion").register_motion("w", {
  collector = "lines",
  extractor = "words",
  filter = "filter_words_after_cursor",
  visualizer = "hint_start",
  action = "jump",
  modes = { "n", "v", "o" },
})
```

--------------------------------

### Multi-Cursor Yank with Smart Motion

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Presets

Enables multi-cursor yanking by allowing users to toggle-select multiple words. Once selected, all highlighted words are yanked. Selection is toggle-based, and ESC cancels the operation.

```text
Press gmy → labels appear on all words → press labels to TOGGLE selection (turns green)
→ press more labels to select more → press Enter → all selected words yanked
```

--------------------------------

### Jump to Marks with Smart Motion

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Presets

Enables jumping to marks by showing labels on all marks (local 'a-z', global 'A-Z'). The user then selects one of the labels to jump to the corresponding mark.

```text
Press g' → labels appear on all marks (a-z local, A-Z global) → select one → jump there
```

--------------------------------

### Configure Plugin Load Order with lazy.nvim

Source: https://github.com/fluxxfield/smart-motion.nvim/wiki/Debugging

Ensures smart-motion.nvim loads after other plugins that might override its keys by setting a higher priority. This is crucial for correct keymap functionality.

```lua
-- lazy.nvim
{
  "FluxxField/smart-motion.nvim",
  priority = 100,  -- load later
}
```